Standard QR - API specification of Interation Operator DKIB (1.0.2)

This document provides the audience with OpenAPI specification for describing DKIB QR code collection's REST APIs. The scope of this document is limited to QR payments in Kyrgyzstan. The target audience of this document is the Developer, Business Analyst and other related Project Team Member of DKIB's client/ team (who has the basic technical know-how of Web technology such as REST or JSON).

There are two major API use cases throughout this document:

• Payments are made between banks of the DKIB network;
• Payments are made between the bank of the DKIB network and the bank of the other Operator's network.

Interaction between DKIB and banks in its network

1. Merchant receives QR code from QR Acquiring and provides it to the customer.
2. Customer or purchaser scans QR code via Payment App.
3. Payment App backend/ Sender bank system parses the information from the code and sends a request for transaction to the Interaction operator.
4. The Interaction Operator stores transaction data and forwards request to the relevant bank.
5. The Receiver bank gets request, makes transaction and sends response to the Interaction Operator.
6. Then the Beneficiary bank notifies merchant about transaction.
7. The operator forwards received response to the Sender Bank/ Payment App.
8. Payment App shows transaction receipt to the customer.

Interaction between the bank of the DKIB network and the bank of the other Operator network

1. Merchant receives QR code from QR Acquiring and provides it to the customer.
2. Customer or purchaser scans QR code via Payment App.
3. Payment App backend/ Sender bank system parses the information from the code and sends a request for transaction to the Interaction operator 1.
4. The Interaction Operator 1 receives transaction data, determines beneficiary bank, and if it is not in its network, it sends request to the relevant Interaction Operator 2.
5. The Interaction Operator 2 gets this request and forwards it to the Beneficiary bank.
6. The Receiver bank gets request, makes transaction and sends response to the Interaction Operator 2.
7. Then the Beneficiary bank notifies merchant about transaction.
8. The Interaction Operator 2 resends response to the Interaction Operator 1.
9. The Interaction Operator 1 redirects response to the Sender bank/ Payment App.
10. Payment App shows transaction receipt to the customer.

The following is a logical flow of network communication:

In general, there will be 5 API requests during the transaction:

• check the details of the recipient,
• create,
• execute,
• update status
• check status.

If the final status was not received at Execute process, the recipient Bank/PSP will have to send an update status request to the Interaction Operator, as soon as the transaction is processed, the Operator in its turn will redirect the update status request to the PSP sender, this is the end of the transaction process.

However, if the final status has not been received, the Sender PSP can send a status check request to the Operator, which in its turn makes the same request to the Beneficiary Bank/PSP.

When interacting between banks of the DKIB network, the interaction will be exclusively between three participants: the Sending bank (Payment Application), the Receiving bank (QR Acquiring) and the DKIB interaction operator.

API Interaction between DKIB and banks in its network

1. First of all, Sender should check requisites so it sends API request to check beneficiary data.
2. DKIB as Interaction operator forwards request to the Beneficiary bank.
3. The Beneficiary bank checks data and sends response to the IO.
4. The Operator redirects this response to the Sender bank/ Payment App.
5. After getting the response the Sender requests transaction creating.
6. The Interaction operator resends this request to the Receiver.
7. Receiver gets request, creates transaction and sends response to the DKIB about creating.
8. The IO DKIB forwards response to the sender.
9. The sender receives response and makes transaction execute request.
10. The IO sends this request to the Beneficiary bank.
11. The Beneficiary bank executes transaction and makes response.
12. The Operator redirects the response to the Payment App.
13. If the final status was not received at the time of the execution, then the Beneficiary bank sends updated status in the Update status request to the Interaction Operator.
14. The Interaction Operator gets final status of transaction from the Receiver bank and sends Update status request to the Sender Bank/PSP.
15. The Sender receives final status and closes transaction, that is the end of process.

There will be 4 roles in the interaction between the banks of the DKIB network and the other Operator, the interaction operators will be intermediaries who redirect requests and responses to each other and/or to the relevant banks.

API Interaction between the bank of the DKIB network and the bank of the other Operator network

Case 1 - Sender is in DKIB Interaction Operator network and Receiver is in the IPC Interaction Operator network.

Case 2 - Sender is in IPC Interaction Operator network and Receiver is in the the DKIB Interaction Operator network.

These schemes work both ways, with the only difference in checking the status of the transaction, because the process of checking the status works differently in the systems of the two interaction operators. .

When two Banks-Members of different Interaction Operators interact, the requests and responses between the Receiving bank and the Sending bank will be the same as when two banks interact with one Operator, with the only difference being that now the requests and responses will not go through one Interaction Operator, but two.

In addition, on the side of the DKIB interaction operator there will be a request/response converter from the DKIB format to the IPC format and back.

Transaction statuses

To form a signature for POST requests, you must form a key pair (RSA 2048) - ReqPrivateKey ReqPublicKey and give ReqPublicKey to the project working group specialists in an encrypted archive.

If the header contains the signature version, by default it comes as H-SIGNING-VERSION = 1, but if the system uses the second version (described below) the header must contain H-SIGNING-VERSION = 2.

1) H-SIGNING-VERSION = 1

To form the header you need to form JWS of the sent payload request with and RSA private key. The signature is formed using ReqPrivateKey.

To from encrypted body you need to form JWE of the sent payload request with and RSA public key. The signature is formed using operator PublicKey.

Example code for generating signature and body:

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSADecrypter;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jwt.EncryptedJWT;
import kg.ctechnology.api.psp.exception.AppException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import javax.servlet.http.HttpServletRequest;
import java.nio.file.Files;
import java.nio.file.Paths;

.....

public String signedPayload(String dtoJson, String privatePath) {
  try{
    String privateKey = new String(Files.readAllBytes(Paths.get(privatePath)));
    RSAKey rsaJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKey);
    JWSSigner signer = new RSASSASigner(rsaJWK);

    JWSObject jwsObject = new JWSObject(
      new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaJWK.getKeyID()).build(),
      new Payload(dtoJson));

    jwsObject.sign(signer);

    return jwsObject.serialize();

  } catch (Exception e){
      throw new AppException(e.getMessage());
    }
}

public String encryptPayload(String dtoJson, String privatePath, String publicPath){
  try {
    String privateKey = new String(Files.readAllBytes(Paths.get(privatePath)));
    String publicKey = new String(Files.readAllBytes(Paths.get(publicPath)));

    RSAKey rsaJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKey);
    RSAKey rsaPublicJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(publicKey);

    JWEEncrypter encrypter = new RSAEncrypter(rsaPublicJWK);

    JWSObject jwsObject = new JWSObject(
      new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaJWK.getKeyID()).build(),
      new Payload(dtoJson));

    JWSSigner signer = new RSASSASigner(rsaJWK);
    jwsObject.sign(signer);
    JWEObject jweObject = new JWEObject(
      new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM)
        .contentType("JWT")
        .build(),
      new Payload(jwsObject));

    jweObject.encrypt(encrypter);

    return jweObject.serialize();

  } catch (Exception ex){
    throw new AppException(ex.getMessage());
  }
}

2) H-SIGNING-VERSION = 2

The OPENSSL DGST SHA256 in base64 format will be used to sign requests.

import com.nimbusds.jose.*;

public String sign(String payload, String privatePath) {
  try{
    Signature signature = Signature.getInstance("SHA256withRSA");
    String privateKeyFile = new String(Files.readAllBytes(Paths.get(privatePath)));
    RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKeyFile);
    PrivateKey privateKey = rsaKey.toPrivateKey();
    signature.initSign(privateKey);
    signature.update(payload.getBytes(StandardCharsets.UTF_8));
    byte[] signatureValue = signature.sign();
    return Base64.encodeBase64String(signatureValue);
  }catch (Exception e){
    throw new AppException(e.getMessage());
  }
}

public void verify(String payload, String sign, String publicPath) {
  try{
    Signature signature = Signature.getInstance("SHA256withRSA");
    String publicKeyFile = new String(Files.readAllBytes(Paths.get(publicPath)));
    RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(publicKeyFile);
    PublicKey publicKey = rsaKey.toPublicKey();
    signature.initVerify(publicKey);
    byte[] data = payload.getBytes(StandardCharsets.UTF_8);
    signature.update(data);
    if(!signature.verify(Base64.decodeBase64(sign))){
      throw new AccessDeniedException("Доступ к системе запрещен");
    }
  }catch (Exception e){
    throw new AppException(e.getMessage());
  }
}

It should be considered that the member banks interact exclusively with the Interaction Operator, i.e. all API requests/responses are received from the Interaction Operator, which in its turn processes all requests/responses and forms new requests/responses on their basis in order to forward them to another member bank.

It should also be noted that the scanning part must transfer all the content data in the acquirer's QR code, regardless of the mandatory nature of this field in the API queries.

Sender Bank/PSP sends requests to the Interaction Operator, and the Interaction Operator returns the response.

Beneficiary Bank/PSP gets request from the Interaction Operator and responses with the related response API's.

It will be implemented on both sides: Operator, Merchant.